src/server/responses/core.ts (1)

2647-2685: 🩺 Stability & Availability | 🔴 Critical | 🏗️ Heavy lift

Emit upstream heartbeats during 429 backoff

The bridge checks upstream activity every 2,000 ms. It increments stallTicks when no adapter event arrives and aborts at ceil(stallTimeoutSec * 1000 / 2000) ticks. Wire heartbeats do not reset this counter.

The retry waits can be silent for up to 600,000 ms. This exceeds the default 300-second core budget and the default 330-second web-search budget.

Apply the fix to these live generators:

• src/server/responses/core.ts:2647-2685
• src/web-search/loop.ts:363-393
• src/images/loop.ts:469-498

Split each sleepWithAbort call into chunks shorter than 2,000 ms, such as 1,000 ms. Yield { type: "heartbeat" } after every chunk, including the final chunk. Add regression coverage for a backoff longer than stallTimeoutSec. The pre-stream retry loops in src/server/responses/core.ts do not require this change.

Update the web-search timeout documentation and tests to state that retry backoff remains live through these upstream heartbeats.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/responses/core.ts` around lines 2647 - 2685, Update the live
retry-backoff loops in src/server/responses/core.ts:2647-2685,
src/web-search/loop.ts:363-393, and src/images/loop.ts:469-498 to split
sleepWithAbort waits into sub-2,000 ms chunks, yielding a heartbeat after every
chunk including the final one, while preserving abort handling; leave pre-stream
retry loops unchanged. Add regression coverage for backoffs exceeding
stallTimeoutSec, and update web-search timeout documentation and tests to
describe continued liveness through upstream heartbeats.

src/images/loop.ts (1)

469-476: 🚀 Performance & Scalability | 🟠 Major | ⚡ Quick win

Keep the retry budget scoped consistently.

src/images/loop.ts initializes rateLimitRetries inside prepareIterationEvents, while one runWithImageBridge request can execute multiple image-loop iterations. This can re-arm the same-key budget and exceed the documented per-request send bound.

• src/images/loop.ts#L469-L476: move the policy and counter to request scope, or explicitly define the budget per iteration.
• structure/04_transports-and-sidecars.md#L235-L235: update the attempts + poolKeys bound if per-iteration scope is intentional.
• devlog/_plan/260802_429_same_target_retry/010_design.md#L95-L110: add a multi-iteration image-bridge regression test.

#!/usr/bin/env bash
set -euo pipefail
rg -n -C 8 'prepareIterationEvents|rateLimitRetries|rateLimitRetryPolicy|HARD_CAP|retryOn429Policy' \
  src/images/loop.ts tests/images/loop.test.ts

As per path instructions, add a focused regression in the flat Bun tests for this src/** behavior change.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/images/loop.ts` around lines 469 - 476, Keep the 429 retry policy and
counter request-scoped in prepareIterationEvents/runWithImageBridge so multiple
image-loop iterations cannot reset the same-key retry budget; preserve the
documented per-request send bound. Update
structure/04_transports-and-sidecars.md:235 to reflect the chosen request-scoped
bound, and extend devlog/_plan/260802_429_same_target_retry/010_design.md:95-110
with a multi-iteration image-bridge regression scenario. Add a focused
regression to the flat Bun tests covering this behavior.

Source: Path instructions

devlog/_plan/260802_429_same_target_retry/010_design.md (1)

47-53: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document the runTurn exception for bridge retries.

src/images/loop.ts enters the adapter.runTurn branch at Lines 355-433 and returns before the HTTP 429 retry loop at Lines 477-513. A key-auth custom runTurn adapter therefore does not receive this HTTP retry policy. State that bridge retries apply to HTTP adapters only and exclude custom runTurn transports.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@devlog/_plan/260802_429_same_target_retry/010_design.md` around lines 47 -
53, Update the retry-policy documentation near the bridge retry references to
state that image/video bridge retries apply only to HTTP adapters. Explicitly
exclude custom adapters using the adapter.runTurn path in src/images/loop.ts,
which returns before the HTTP 429 retry loop; do not imply that runTurn
transports receive the same wait-and-replay behavior.

src/server/responses/core.ts (1)

2668-2707: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Await terminal-continuation body cancellation before the backoff.

At Line 2679, response.body.cancel() is detached with void. sleepWithAbort() then starts at Line 2681 while cancellation can still be pending. Under repeated 429 responses, unread bodies can remain active through the retry wait and replay.

Await cancellation before sleeping.

Proposed fix

-        try { void response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
+        try { await response.body?.cancel().catch(() => {}); } catch { /* already closed */ }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/responses/core.ts` around lines 2668 - 2707, In the
terminal-continuation retry loop, update the response body cleanup before
sleepWithAbort to await response.body cancellation rather than detaching the
promise. Preserve the existing safe handling for absent or already-closed
bodies, and ensure the backoff starts only after cancellation has settled.

src/server/responses/core.ts (1)

2617-2666: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Reduce the duplicated recovery-label expression in fetchContinuation.

Lines 2638 and 2647 both derive the same label from replay. The second one additionally merges the transient-retry kind. The logic is correct, but the label rule now lives in two places, so a future change to the label (for example a distinct kind for continuation replays) can easily update only one branch.

♻️ Optional consolidation

       if (continuationEstimate !== undefined) logCtx.usageLogInputTokens = continuationEstimate;
+      const replayKind: AttemptRecoveryKind | undefined = replay ? "rate-limit-429" : undefined;
       try {
         if (activeAdapter.fetchResponse) {
-          noteAttemptSend(logCtx.activeAttempt, continuationEstimate, replay ? "rate-limit-429" : undefined);
+          noteAttemptSend(logCtx.activeAttempt, continuationEstimate, replayKind);
           return await activeAdapter.fetchResponse(continuationRequest, {
@@
         return await fetchWithResetRetry(
           recovery => {
-            noteAttemptSend(logCtx.activeAttempt, continuationEstimate, recovery ?? (replay ? "rate-limit-429" : undefined));
+            noteAttemptSend(logCtx.activeAttempt, continuationEstimate, recovery ?? replayKind);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/responses/core.ts` around lines 2617 - 2666, Consolidate the
replay-derived recovery label in fetchContinuation by computing it once before
the fetch branches, then reuse that value in both noteAttemptSend calls while
preserving the fetchWithResetRetry recovery override behavior.

src/config.ts (1)

1144-1158: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Include the accepted range in the warning for out-of-range numbers.

The validators at Lines 1146-1148 reject both wrong types and out-of-range numbers, but the warning at Line 1157 reports only typeof value. A user who writes "attempts": 999 sees providers.x.retryOn429.attempts (number) is invalid, which gives no hint about the accepted bound. Numbers and booleans cannot carry secret material, so the range can be stated safely while the value itself stays unlogged.

♻️ Proposed diagnostic improvement

-    const fields: Array<[string, (value: unknown) => boolean]> = [
-      ["enabled", value => typeof value === "boolean"],
-      ["attempts", value => typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 20],
-      ["intervalMs", value => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 600_000],
-      ["maxIntervalMs", value => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 600_000],
-      ["respectRetryAfter", value => typeof value === "boolean"],
+    const fields: Array<[string, (value: unknown) => boolean, string]> = [
+      ["enabled", value => typeof value === "boolean", "expected boolean"],
+      ["attempts", value => typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 20, "expected integer 1-20"],
+      ["intervalMs", value => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 600_000, "expected integer 100-600000"],
+      ["maxIntervalMs", value => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 600_000, "expected integer 100-600000"],
+      ["respectRetryAfter", value => typeof value === "boolean", "expected boolean"],
     ];
     const cleaned: Record<string, unknown> = {};
-    for (const [key, isValid] of fields) {
+    for (const [key, isValid, expectation] of fields) {
       const value = policyRecord[key];
       if (value === undefined) continue;
       if (isValid(value)) cleaned[key] = value;
       // Log only the received type, never the value (provider config can hold secrets).
-      else console.warn(`⚠️  config.json providers.${name}.retryOn429.${key} (${typeof value}) is invalid — ignoring the field`);
+      else console.warn(`⚠️  config.json providers.${name}.retryOn429.${key} (${typeof value}) is invalid — ${expectation}; ignoring the field`);
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/config.ts` around lines 1144 - 1158, Update the validation warning in the
retry policy field loop around the `fields` validators to include the accepted
ranges for numeric keys such as `attempts`, `intervalMs`, and `maxIntervalMs`,
while retaining type-only reporting and never logging the received value. Keep
boolean warnings unchanged and preserve the existing validation and
field-cleaning behavior.

src/images/loop.ts (1)

483-515: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Bound pre-header 429 retries before creating SSE

For non-runTurn image requests and all web-search requests, prepareIterationDrained consumes the retry heartbeat before bridgeToResponsesSSE is created. The client receives no response headers while same-target 429 retries wait. The default policy can wait 3 minutes; valid configuration can wait up to 200 minutes (20 × 600_000ms). Bound the aggregate eager-phase wait to the request header budget, or move these retries into the live produce() phase. Apply the fix to both loops. runTurn image requests already skip the eager drain.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/images/loop.ts` around lines 483 - 515, Bound same-target 429 retry
waiting during the eager preparation phase so it cannot exceed the request
header-timeout budget before SSE creation, or defer the retries into the live
produce phase. Apply the corresponding fix to the retry loop in
src/images/loop.ts lines 483-515 and src/web-search/loop.ts lines 380-412;
preserve the existing runTurn image behavior, which already skips eager
draining.

docs-site/src/content/docs/ja/guides/providers.md (1)

146-146: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the Markdown table separator.

Line 146 uses --- | --- | without a leading pipe. markdownlint-cli2 reports MD055 for this line. Change it to | --- | --- |.

Proposed fix

- --- | --- |
+| --- | --- |

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/ja/guides/providers.md` at line 146, Update the
Markdown table separator at the affected location from “--- | --- |” to “| --- |
--- |” so it has the required leading pipe and satisfies markdownlint MD055.

Source: Linters/SAST tools

docs-site/src/content/docs/guides/providers.md (1)

347-354: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Synchronize the locale guides with the Copilot wire rules.

Add the Copilot routing paragraph before the Cursor section in ja (line 268), ko (line 269), ru (line 281), and zh-cn (line 249). Include the GPT-5 model list, openai-responses routing, openai-chat behavior for other Copilot models, modelAdapters precedence, and the gpt-5.4-nano override example.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/guides/providers.md` around lines 347 - 354,
Synchronize the localized provider guides by adding the Copilot routing
paragraph before the Cursor section in the ja, ko, ru, and zh-cn guides.
Preserve the complete behavior described in the source paragraph: list all
specified GPT-5 models, route them through openai-responses by default, keep
other Copilot models on openai-chat, document modelAdapters precedence, and
include the gpt-5.4-nano override example.

Source: Path instructions

docs-site/src/content/docs/ja/guides/providers.md (1)

145-151: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Restore the leading pipe on the delimiter row of the API key catalog table.

Line 146 is --- | --- |. The leading | is missing, while the header row at Line 145 has it. markdownlint flags this as MD055 (table-pipe-style). remark/CommonMark can then fail to recognize the delimiter row, so the whole API-key catalog table risks rendering as literal text instead of a table. The English source at docs-site/src/content/docs/guides/providers.md:218 uses | --- | --- |.

Note: the same malformed shape already exists at unchanged Lines 246 and 301 of this file. Fixing those too keeps the page consistent, but only Line 146 is inside this change.

📝 Proposed fix for the delimiter row

 | プロバイダー | ベース URL |
- --- | --- |
+| --- | --- |
 | **OpenAI (API キー)** | `https://api.openai.com/v1` |

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/ja/guides/providers.md` around lines 145 - 151,
Restore the leading pipe on the delimiter row immediately beneath the API-key
catalog table header so it matches the header and English source format, using a
complete `| --- | --- |` row. Also correct the same malformed delimiter rows at
the unchanged table sections around the later provider tables to keep the page
consistent.

Sources: Path instructions, Linters/SAST tools

src/server/responses/core.ts (1)

2495-2503: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

The image-tier bias discovered by the main recovery loop is lost for the terminal-guard continuation.

imageTierBias at Line 2503 is scoped to the if (!upstreamResponse.ok) block and is bumped to 1 at Line 2716 when the main flow needs a smaller image tier to clear an Anthropic 413. fetchTerminalGuardContinuation declares its own, independent imageTierBias at Line 2770, starting at 0.

Because fetchContinuation (Line 2777) keys its cache on sameTargetParsed === nextParsed, and nextParsed is always a different object from parsed, the very first continuation call always rebuilds the request (Line 2784) using the continuation's own imageTierBias, not the value the main flow already proved necessary. If the same oversized images are still present, the continuation's first attempt gets a redundant 413, and only its own shouldAttemptImageTierRetry check (Lines 2952-2962) rediscovers the tier reduction on a second attempt.

This self-recovers (matches the shared rateLimitPolicy/rateLimitRetries pattern already applied at Line 2495-2496 for the same producer/consumer boundary), so it costs one avoidable round trip and one avoidable 413 rather than a hard failure. Hoist the discovered bias the same way the retry budget was hoisted.

🐛 Proposed fix to share the discovered image tier with the continuation

   const rateLimitPolicy = rateLimitRetryPolicyFor(route.provider);
   let rateLimitRetries = 0;
+  // Shared with fetchTerminalGuardContinuation below: an image-tier reduction that let the
+  // main request clear a 413 must not be forgotten on the very next continuation build.
+  let sharedImageTierBias = 0;
   if (!upstreamResponse.ok) {

         imageRetryAttempted = true;
         imageTierBias = 1;
+        sharedImageTierBias = 1;
         invalidateSameTargetRequest();

   const fetchTerminalGuardContinuation = async function* (nextParsed: OcxParsedRequest): AsyncGenerator<AdapterEvent> {
-    let imageTierBias = 0;
+    let imageTierBias = sharedImageTierBias;
     let response: Response | undefined;

Also applies to: 2714-2718, 2769-2789

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/responses/core.ts` around lines 2495 - 2503, Hoist imageTierBias
to the same shared scope as rateLimitPolicy and rateLimitRetries, initialize it
once before the main recovery loop, and remove the independent declaration
inside fetchTerminalGuardContinuation. Keep the existing updates in the main
recovery flow and ensure fetchContinuation reuses the discovered bias when
rebuilding continuation requests.

gui/src/i18n/ko.ts (1)

577-579: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use Korean wording for request-rate limits.

요금 제한 describes a fee or charge restriction. These labels describe HTTP request throttling. Use wording consistent with the existing pws.healthLabel.rateLimited translation.

Proposed wording

-  "logs.detail.attempt.recovery.key429": "키 요금 제한 (429)",
-  "logs.detail.attempt.recovery.rateLimit429": "요금 제한 (429)",
-  "logs.detail.attempt.recovery.anthropicOauth429": "Anthropic OAuth 요금 제한 (429)",
+  "logs.detail.attempt.recovery.key429": "키 요청 한도 초과 (429)",
+  "logs.detail.attempt.recovery.rateLimit429": "요청 한도 초과 (429)",
+  "logs.detail.attempt.recovery.anthropicOauth429": "Anthropic OAuth 요청 한도 초과 (429)",

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@gui/src/i18n/ko.ts` around lines 577 - 579, Update the three recovery labels
under logs.detail.attempt.recovery.key429, rateLimit429, and anthropicOauth429
to use the Korean request-throttling wording established by
pws.healthLabel.rateLimited instead of 요금 제한, while preserving the existing 429
context and Anthropic OAuth naming.

gui/src/pages/Logs.tsx (1)

317-323: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Add a localized fallback for unknown recovery kinds.

validCachedLogs checks only top-level fields. A stale or malformed cached row can contain a recovery kind that is not in RECOVERY_KIND_KEYS. The lookup then returns undefined, and t(recoveryKindKey(kind)) can break the log detail dialog or render an invalid label.

Add a localized fallback or validate nested cached recovery kinds before this lookup. Add the fallback key to every locale catalog.

As per path instructions, GUI user-visible strings must go through i18n locale files.

Proposed fix

 function recoveryKindKey(kind: AttemptRecoveryKind) {
-  return RECOVERY_KIND_KEYS[kind];
+  return RECOVERY_KIND_KEYS[kind] ?? "logs.detail.attempt.recovery.unknown";
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@gui/src/pages/Logs.tsx` around lines 317 - 323, Update recoveryKindKey to
return a valid localized fallback key when kind is absent from
RECOVERY_KIND_KEYS, and add that fallback translation key to every locale
catalog. Ensure t(recoveryKindKey(kind)) always receives a defined key without
changing valid recovery-kind mappings.

Source: Path instructions